fix: Improve Python project detection and entrypoint resolution by vdusek · Pull Request #1010 · apify/apify-cli

vdusek · 2026-01-27T14:03:03Z

Summary

Simplified Python project detection to discover packages purely by looking for directories with __init__.py files.
Derived default Actor name from the Python package name.
Added near-miss detection with actionable fix suggestions for broken Python packages.
Subpackage detection.
Added 29 unit tests covering the full detection matrix.

Python project detection

Detect Python projects purely via package structure: directories with valid Python identifier names containing __init__.py.
Skip hidden directories (.venv) and underscore-prefixed directories (__pycache__, _internal) as they shouldn't be main entrypoints.
When src/ is itself a package (has __init__.py), treat nested directories as subpackages, not separate top-level packages.

Actor name derivation

For Python projects, the default Actor name is derived from the package name.
Entrypoint src.my_package → extracts my_package → sanitizes to my-package.
Entrypoint my_package → sanitizes to my-package.

Runtime precedence

Node.js (package.json) takes precedence over Python indicators when both exist.

Error handling

Near-miss: invalid name + __init__.py — suggests renaming the directory (e.g., my-package/ → my_package/)
Near-miss: valid name + .py files but no __init__.py — suggests adding __init__.py
Near-miss: invalid name + .py files but no __init__.py — suggests both renaming and adding __init__.py
Multiple packages — lists all found packages and guides user to ensure only one top-level package exists
No package and no Python files — returns Unknown (not a Python project)

Test plan

29 tests covering the full parametrized matrix: {CWD with dashes | underscores} × {flat | src container} × {valid | invalid pkg name} × {__init__.py + .py | .py only | no .py} = 24 cases, plus 5 individual cases:
- JavaScript and Python coexistence (JS takes precedence)
- Multiple flat packages error
- Multiple packages in src/ error
- Loose .py files without package structure
- No Python project at all (Unknown)
All existing local tests pass

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

Copilot

Pull request overview

This pull request enhances Python project detection in the Apify CLI to support standard Python package layouts without requiring specific directory names. The changes enable automatic package discovery and provide better error messages for common configuration issues.

Changes:

Implemented flexible Python project detection based on pyproject.toml, requirements.txt, or presence of .py files
Added automatic package discovery that searches for valid Python packages in the current directory and src/ subdirectory
Introduced smart entrypoint resolution that automatically selects the entrypoint when exactly one package is found
Enhanced error messages with clear guidance for scenarios including no packages found, multiple packages found, and mixed Python/Node.js projects
Maintained backwards compatibility with existing projects using src/__main__.py

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`src/lib/hooks/useCwdProject.ts`	Core implementation of enhanced Python project detection including helper functions for package discovery, validation, and entrypoint resolution; added mixed project detection
`test/lib/hooks/useCwdProject.test.ts`	Comprehensive new test suite covering flat packages, src container structures, subpackages, multiple packages error cases, edge cases, and mixed project detection
`test/local/__fixtures__/commands/run/python/prints-error-message-on-project-with-no-detected-start.test.ts`	Updated to remove `requirements.txt` to properly test the "no detection" scenario with the new detection logic

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/lib/hooks/useCwdProject.ts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: remove references to unsupported --entrypoint flag The --entrypoint flag doesn't exist yet, so remove mentions of it from error messages. Updated messages now guide users to fix their project structure instead. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> fix: prefer Node.js over Python when both indicators exist When a project has both package.json and Python indicators (like requirements.txt), prefer Node.js detection instead of throwing an error. This simplifies the user experience for mixed projects. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- dirExists now actually checks for directories using stat().isDirectory() - Warn when detected package is missing __main__.py (python -m will fail) - Rename suggestion handles all invalid chars, not just hyphens - Add tests for src/ as a package and __main__.py warning - Document JS precedence over Python with detailed comment - Fix tests to reflect that requirements.txt no longer affects detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vladfrangu · 2026-02-10T11:04:47Z

src/lib/hooks/useCwdProject.ts

+		throw new Error(
+			`Multiple Python packages found:\n${packageList}\n\n` +
+				'Apify CLI cannot determine which package to run.\n' +
+				'Please ensure only one top-level package exists in your project.',


Technically speaking they can have multiple right, and they'd need to use --entrypoint to select one?

Exactly. However, since --entrypoint hasn't been implemented yet (unless I'm mistaken), I didn't mention it there. Once it's available, it would be great to update this - I'll add a comment to #766.

--entrypoint exists! #766 is related to defining said entrypoint starts in actor.json so we don't have to do this jumble detection method (you just write the command to run from the root of your actor)

Oh, got it, thanks! So I will update the error message then, perfect.

vdusek added this to the 133rd sprint - Tooling team milestone Jan 27, 2026

vdusek self-assigned this Jan 27, 2026

vdusek added adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team. labels Jan 27, 2026

github-actions bot added the tested Temporary label used only programatically for some analytics. label Jan 27, 2026

vdusek changed the title ~~feat: improve Python project detection and entrypoint resolution~~ fix: Improve Python project detection and entrypoint resolution Jan 27, 2026

vdusek force-pushed the feat/improve-python-project-detection branch from b1954c2 to 27ca7f5 Compare February 5, 2026 09:59

vdusek requested a review from Copilot February 5, 2026 10:09

Copilot started reviewing on behalf of vdusek February 5, 2026 10:10 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

src/lib/hooks/useCwdProject.ts Outdated Show resolved Hide resolved

src/lib/hooks/useCwdProject.ts Outdated Show resolved Hide resolved

fix: Improve Python project detection and entrypoint resolution

9a23d04

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vdusek force-pushed the feat/improve-python-project-detection branch from 09d051e to 9a23d04 Compare February 5, 2026 10:42

vdusek marked this pull request as ready for review February 5, 2026 10:55

vdusek requested a review from vladfrangu as a code owner February 5, 2026 10:55

vdusek and others added 2 commits February 6, 2026 15:46

Better handle all possible cases and add test matrix

6ac846d

vladfrangu approved these changes Feb 10, 2026

View reviewed changes

vdusek mentioned this pull request Feb 10, 2026

Actor Entrypoint configuration #766

Open

improve error message when multiple pkgs

271958d

vdusek merged commit f0704d3 into master Feb 10, 2026
61 of 64 checks passed

vdusek deleted the feat/improve-python-project-detection branch February 10, 2026 12:55

claude bot added the claude-code-assisted label Feb 11, 2026

vdusek mentioned this pull request Feb 12, 2026

fix: Replace "src" with meaningful package names in Python templates apify/actor-templates#638

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Improve Python project detection and entrypoint resolution#1010

fix: Improve Python project detection and entrypoint resolution#1010
vdusek merged 5 commits intomasterfrom
feat/improve-python-project-detection

vdusek commented Jan 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

vladfrangu Feb 10, 2026

Uh oh!

vdusek Feb 10, 2026

Uh oh!

vladfrangu Feb 10, 2026

Uh oh!

vdusek Feb 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

vdusek commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Python project detection

Actor name derivation

Runtime precedence

Error handling

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

vladfrangu Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

vdusek Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

vladfrangu Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

vdusek Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vdusek commented Jan 27, 2026 •

edited

Loading